package za.org.jcicada.genss.sensor;

import java.io.Serializable;
import java.util.Observer;

/**
 * Interface for sampling strategies. A sampling strategy is created to monitor
 * a particular sensor. At a rate determined by the stratgy, it samples the current
 * state of the sensor and notifies a listener via a callback mechanism.
 * 
 * @author rcrida
 *
 * Created on November 11, 2008, 09:52
 */


/**
 * Interface for sampling strategy objects.
 */
public interface ISamplingStrategy extends Observer, Serializable {
    
    /**
     * This interface should be implemented by objects wishing to receive an update
     * notification from a sampling strategy on a sensor.
     */
    public interface IListener {
        
        /**
         * Called when a sampling strategy indicates that the observer
         * should be updated on the state of the sensor.
         * @param sensorURN the sensor URI.
         * @param value the details of the sensor that has been updated.
         */
        void update(SensorURN sensorURN, Object value);
    }
    
    /**
     * @return the sensorURI that this strategy is for
     */
    public SensorURN getSensorURN();
    
    /**
     * This method is called when a period strategy is being configured
     * or periodically after that.
     * @param self This object.
     * @param time is the time at which the next sample was requested
     * @return the desired time for the next sample
     */
    long periodic(long time);
    
    /**
     * Get the sensor that this sampling strategy is monitoring.
     * @return the sensor
     */
    ISensor getSensor();

    /**
     * Attach the sampling strategy to a sensor after first ensuring that it
     * is not attached to another sensor.
     * @param sensor the sensor to attach to.
     * @return true if successfully attached
     */
    boolean attachToSensor(ISensor sensor);
    
    /**
     * Detach this sampling strategy from any sensor it is currently attached
     * to.
     */
    void detachFromSensor();
    
    /**
     * Specify a listener object to be informed when update is called.
     * @param listener object is informed of updates
     */
    void setListener(IListener listener);
    
    /**
     * Create a string array representation of this object. Suitable for use
     * with String[] constructor.
     * @return string representation of all args of this object
     */
    String[] toStringArray();
    
}
